<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Deployment</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_deploy.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Deployment </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Once the DynamoRIO distribution contents are unpacked (see <a class="el" href="release_notes.html#sec_package">Distribution Contents</a>), configuration and execution of applications under DynamoRIO is handled by a set of libraries and tools. On Windows, the tools are <code>drconfig.exe</code>, <code>drrun.exe</code>, and <code>drinject.exe</code>. The corresponding libraries (whose APIs are exposed by the tools) are <code>drconfiglib.dll</code> and <code>drinjectlib.dll</code> with header files <code><a class="el" href="dr__config_8h.html" title="Deployment API for DynamoRIO. Use these functions to register processes to run under DynamoRIO...">dr_config.h</a></code> and <code><a class="el" href="dr__inject_8h.html" title="Injection API. Use these functions to launch processes under the control of DynamoRIO.">dr_inject.h</a></code>. On Linux, the tools are named <code>drconfig</code>, <code>drrun</code>, and <code>drinject</code>, and the libraries are <code>libdrconfiglib.so</code> and <code>libdrinjectlib.so</code>.</p>
<p>When using DynamoRIO as a third-party disassembly library (see <a class="el" href="page_standalone.html">IA-32/AMD64 Disassembly Library</a>), no deployment is needed, as DynamoRIO does not control a target application when used as a regular library.</p>
<h1><a class="anchor" id="win_deploy"></a>
Windows Deployment</h1>
<p>There are two methods for running a process under DynamoRIO: the one-time configure-and-run, and the two-step separate configuration and execution. The <code>drrun.exe</code> tool supports the first, simpler model, while the <code>drconfig.exe</code> and <code>drinject.exe</code> tools support the second, more powerful model. The <code>drconfig.exe</code> tool, or the corresponding the <code>drconfiglib.dll</code> library, can also be used to <a class="el" href="using.html#sec_comm">nudge</a> running processes.</p>
<p>Configuration information is stored in files in the current user's profile directory, which is obtained from the environment variable <code>USERPROFILE</code>. Thus, configurations are persistent across reboots and are private to each user. If the <code>DYNAMORIO_CONFIGDIR</code> environment variable is set, its value is used instead of <code>USERPROFILE</code>. If neither is set, a temp directory will be used when creating new configuration files for configure-and-run execution.</p>
<p>DynamoRIO also supports global configurations, which are stored in the "config" subdirectory of the directory specified by the <code>DYNAMORIO_HOME</code> registry value in the registry key <code>\HKLM\SOFTWARE\DynamoRIO\DynamoRIO</code> (or for 32-bit on 64-bit Windows (WOW64) <code>\HKLM\SOFTWARE\Wow6432Node\DynamoRIO\DynamoRIO</code>). Setting that <code>DYNAMORIO_HOME</code> value and creating the directory it points to must be done manually. The provided tools support reading and writing both local and global configuration files, and automatically creating the local directory. DynamoRIO gives local files precedence when both exist. Note that applications that do not have a <code>USEPROFILE</code> environment variable can be controlled using <code>DYNAMORIO_CONFIGDIR</code> or global configurations. Also note that by default <code>USERPROFILE</code> is not set over cygwin ssh and must be explicitly set in the shell startup files.</p>
<p>Configurations are per-process, with the basename of the process used for identification (e.g., <code>calc.exe</code>). One-time configuration also uses the process id to specify that the configuration is for that process instance only.</p>
<p>As an example, assume you have unpacked the DynamoRIO distribution and your current directory is its base directory. Run <code>calc.exe</code> with the bbsize sample client using the following configure-and-run command: </p>
<div class="fragment"><div class="line">bin32/drrun.exe -c samples/bin32/bbsize.dll -- calc</div>
</div><!-- fragment --><p>To use system-wide injection, allowing for an application to be run under DynamoRIO regardless of how it is invoked, configure the application first (-syswide_on requires administrative privileges): </p>
<div class="fragment"><div class="line">bin32/drconfig.exe -reg calc.exe -syswide_on -c samples/bin32/bbsize.dll</div>
</div><!-- fragment --><p>The next time <code>calc.exe</code> is started by the current user, it will run under DynamoRIO with the bbsize client.</p>
<p>To unregister <code>calc.exe</code>, issue the following command: </p>
<div class="fragment"><div class="line">bin32/drconfig.exe -unreg calc.exe</div>
</div><!-- fragment --><p>Invoke any of the <code>drconfig.exe</code>, <code>drrun.exe</code>, or <code>drinject.exe</code> tools with no arguments to see the full list of options available.</p>
<p>By default, DynamoRIO follows into all child processes, with the parent's settings inherited by the child if there is no configuration set up ahead of time for the child application. To instead only follow children that are configured (via <code>drconfig.exe</code>), use the <a class="el" href="using.html#op_children">-no_follow_children</a> runtime option.</p>
<p>To <a class="el" href="using.html#sec_comm">nudge</a> all instances of <code>calc.exe</code> running under DynamoRIO with argument "5", use: </p>
<div class="fragment"><div class="line">bin32/drconfig.exe -nudge calc.exe 0 5</div>
</div><!-- fragment --><p> This will result in a nudge event with argument=5 delivered to the client callback registered with <a class="el" href="dr__events_8h.html#a9037603d0bd5bfca4198011adb8d10eb">dr_register_nudge_event()</a> in all <code>calc.exe</code> processes running under DynamoRIO. The third argument, 0, is an ID supplied at registration which uniquely identifies the target client (see dr_deploy.h for details).</p>
<p>To view 32-bit or WOW64 processes running under DynamoRIO the <code>drview.exe</code> tool can be used. The bin64 version will display both 32-bit and 64-bit processes and will indicate which are 32-bit. The bin32 version will display 64-bit processes but is unable to determine whether DynamoRIO is present.</p>
<dl class="section attention"><dt>Attention:</dt><dd>Note that on Windows NT a reboot is required after using -syswide_on or -syswide_off.</dd></dl>
<p>DynamoRIO uses the <code>\HKLM\SOFTWARE\Microsoft\Windows\Windows NT\CurrentVersion\AppInit_DLLs</code> key (for 32-bit on 64-bit Windows (WOW64), <code>\HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\Windows\AppInit_DLLs</code>) for -syswide_on to inject into new processes without having to directly launch them <code>drrun.exe</code> or <code>drinject.exe</code>. For injection to work, the registered process must statically link to user32.dll (only a few small non-graphical windows applications don't link user32.dll). If a target application does not link to user32.dll, DynamoRIO can still inject if the process is launched with <code>drinject.exe</code> or if the parent process (usually cmd.exe or explorer.exe for user launched processes) is running under DynamoRIO. The drinject.exe tool uses the configuration information set by <code>drconfig.exe</code> for the target application.</p>
<dl class="section attention"><dt>Attention:</dt><dd>The -syswide_on, -syswide_off, use of global configuration files, and nudging certain processes may require administrative privileges. On Windows Vista or higher, if UAC is enabled, use an elevated (runas admin) process. When using <code>drconfig.exe</code> and <code>drrun.exe</code> in these scenarios, be sure that the cmd shell being used was started with elevated permissions.</dd></dl>
<h1><a class="anchor" id="lin_deploy"></a>
Linux Deployment</h1>
<p>Once DynamoRIO has been unpacked, the same set of helper binaries as on Windows provide flexibility in configuring and executing applications. The <a class="el" href="release_notes.html#limits_linux_preload">LD_PRELOAD</a> injection mechanism and the <a class="el" href="API_BT.html#sec_startstop">app_start()/app_stop()</a> interface are currently the only supported methods of running applications under DynamoRIO on Linux.</p>
<p>There are two methods for invoking an application under DynamoRIO:</p>
<ol type="1">
<li>Configure and launch in one step via <code>drrun</code> </li>
<li>Configure via <code>drconfig</code> and launch via <code>drinject</code> </li>
</ol>
<p>As an example of the simpler method, the following command runs <code>ls</code> under DynamoRIO with the bbsize sample client: </p>
<div class="fragment"><div class="line">% bin32/drrun -c samples/bin32/libbbsize.so -- ls</div>
</div><!-- fragment --><p> Run <code>drrun</code> with no options to get a list of the options and environment variable shortcuts it supports. To disable following across child execve calls, use the <a class="el" href="using.html#op_children">-no_follow_children</a> runtime option.</p>
<p>Use the tools in <code>bin32/</code> for 32-bit applications and the tools in <code>bin64/</code> for 64-bit applications.</p>
<p>The two-step method allows for greater control over child processes. The <code>drconfig</code> tool writes a configuration file for a given application name. DynamoRIO reads its options from the configuration file at runtime. Once each process name is configured, the <code>drinject</code> tool can be used to invoke the parent process. The <code>drrun</code> tool can also be used but it creates a temporary configuration file that will override settings requested via <code>drconfig</code>. The configuration file for each application is stored in <code>$DYNAMORIO_CONFIGDIR/.dynamorio/&lt;appname&gt;.config32</code> (or a <code>config64</code> suffix for 64-bit). If <code>DYNAMORIO_CONFIGDIR</code> is not set, <code>$HOME/.dynamorio/&lt;appname&gt;.config32</code> is used; if neither is set, a temp directory will be used when creating new configuration files for configure-and-run execution.</p>
<p>DynamoRIO also supports global configuration files in <code>/etc/dynamorio/&lt;appname&gt;.config32</code> when a local configuration file is not found. <code>drconfig</code> does not support directly writing a global config file but such files can be copied from or modeled on local files.</p>
<p>If a target application executes an <code>execve</code> that discards the <code>HOME</code> environment variable, the resulting process will still run under DynamoRIO control with the same settings as the parent process. Use <code>DYNAMORIO_CONFIGDIR</code> or global configuration files to specify separate options for such a child process.</p>
<p>If a target application binary has suid or sgid bits set, <code>drrun</code> will be unable to inject into it. You'll need to use /etc/ld.so.preload as described in the <a class="el" href="release_notes.html#limits_linux_preload">Limitations</a> section.</p>
<p>When running scripts it is best to explicitly invoke the interpreter rather than invoking the script directly:</p>
<div class="fragment"><div class="line">% bin64/drrun -- /bin/bash myscript.sh</div>
</div><!-- fragment --><p>To <a class="el" href="using.html#sec_comm">nudge</a> a process with pid <code>targetpid</code> running under DynamoRIO and pass argument "5" to the nudge callback, use the <code>nudgeunix</code> tool: </p>
<div class="fragment"><div class="line">bin32/nudgeunix -pid targetpid -client 0 5</div>
</div><!-- fragment --><p> This will result in a nudge event with argument=5 delivered to the client callback registered with <a class="el" href="dr__events_8h.html#a9037603d0bd5bfca4198011adb8d10eb">dr_register_nudge_event()</a> in the target process. The 0 argument is an ID supplied at registration which uniquely identifies the target client (see dr_deploy.h for details). If you used the -c argument to drrun or drconfig to register the client, the client's id defaults to 0.</p>
<h1><a class="anchor" id="client_ops"></a>
Passing Options to Clients</h1>
<p>All of the earlier examples did not need to pass any arguments to the client. When using the -c argument to set the client, all arguments between the client path and the double dash are passed to the client. When using the -client argument to drrun, the third argument following -client is passed through to the client. For example, all these invocations of drrun pass '-op1 -op2 "value with spaces"' to the client:</p>
<div class="fragment"><div class="line">bin32/drrun.exe -c libmyclient.dll -op1 -op2 \<span class="stringliteral">&quot;value with spaces\&quot; -- calc</span></div>
<div class="line"><span class="stringliteral">bin32/drrun.exe -client myclient.dll 0 &#39;-op1 -op2 &quot;</span>value with spaces<span class="stringliteral">&quot;&#39; -- calc</span></div>
</div><!-- fragment --><p>On Linux:</p>
<div class="fragment"><div class="line">bin32/drrun -c libmyclient.so -op1 -op2 \<span class="stringliteral">&quot;value with spaces\&quot; -- ls</span></div>
<div class="line"><span class="stringliteral">bin32/drrun -client libmyclient.so 0 &#39;-op1 -op2 &quot;</span>value with spaces<span class="stringliteral">&quot;&#39; -- ls</span></div>
</div><!-- fragment --><p>When using a two-step model, the options are passed to <code>drconfig:</code> </p>
<div class="fragment"><div class="line">bin32/drconfig.exe -reg calc.exe -c myclient.dll -op1 -op2 \<span class="stringliteral">&quot;value with spaces\&quot;</span></div>
<div class="line"><span class="stringliteral">bin32/drconfig.exe -reg calc.exe -client myclient.dll 0 &#39;-op1 -op2 &quot;</span>value with spaces<span class="stringliteral">&quot;&#39;</span></div>
</div><!-- fragment --><p>The client can call <a class="el" href="dr__tools_8h.html#a10831623706378cfc3082c0e27e31c4c">dr_get_options()</a> to retrieve the option string passed to it.</p>
<p>Client options are not allowed to contain semicolons. Additionally, the client option string combined with the path to the client library cannot contain all three quote characters (', ", `) simultaneously.</p>
<h1><a class="anchor" id="multi_client"></a>
Multiple Clients</h1>
<p>DynamoRIO does support multiple clients. It is each client's responsibility, however, to ensure compatibility with other clients. DynamoRIO makes no attempt to force cooperation among clients. For example, instruction stream modifcations made by one client are visible to other clients. Systems employing multiple clients must be aware of such interactions and design accordingly.</p>
<p>Client registration requires users to specify the <em>priority</em> of each client. DynamoRIO calls each client's <a class="el" href="dr__api_8h.html#a20a4dc9da7f6bb9121e30bb3570c6961">dr_init()</a> routine sequentially according to this priority. Clients with a numerically lower priority value are called first and therefore given the first opportunity to register callbacks (the client with priority 0 is called first). Since DynamoRIO delivers event callbacks sequentially, client priority and the order of event registration is important. For a given event, the <em>first</em> registered callback is called <em>last</em>. This scheme gives precedence to the first registered callback since that callback is given the final opportunity to modify the instruction stream or influence DynamoRIO's operation.</p>
<h1><a class="anchor" id="tool_frontend"></a>
End-User Tools</h1>
<p>A client can be packaged up with DynamoRIO to create an end-user tool. For many tools, a separate front-end executable is not necessary, and <code>drrun</code> is sufficient. Using <code>drrun</code> for a tool is made simpler by the <code>-t</code> option. To use the option, first create a file in the <code>tools</code> subdirectory of the root of the DynamoRIO installation called <code>toolname.drrun32</code> or <code>toolname.drrun64</code>, depending on the target architecture. Here, <code>toolname</code> is the desired external name of the tool. This file should contain one of the following lines:</p>
<div class="fragment"><div class="line">CLIENT_ABS=/absolute/path/to/client</div>
</div><!-- fragment --><p>or</p>
<div class="fragment"><div class="line">CLIENT_REL=relative/path/to/client/from/DynamoRIO/root</div>
</div><!-- fragment --><p>This enables <code>drrun</code> to locate the tool's client library.</p>
<p>The file can also modify the default DynamoRIO runtime options (see <a class="el" href="using.html#sec_options">Fine-Tuning DynamoRIO: Runtime Parameters</a>) via <code>DR_OP=</code> lines. Each line contains only one option string token. For example:</p>
<div class="fragment"><div class="line">DR_OP=-persist</div>
<div class="line">DR_OP=-persist_dir</div>
<div class="line">DR_OP=c:\\path with spaces\\subdir</div>
</div><!-- fragment --><p>Tool options can also be specified, but normally the defaults should be set up appropriately in the client itself:</p>
<div class="fragment"><div class="line">TOOL_OP=-custom_op1</div>
<div class="line">TOOL_OP=-custom_op2</div>
</div><!-- fragment --><p>Lines beginning with <code>#</code> are considered comments.</p>
<p>When <code>drrun</code> is passed the option string <code>-t toolname</code>, it looks for <code>tools/toolname.drrun64</code> or <code>tools/toolname.drrun32</code> and reads the file to determine the client library to use and the default DynamoRIO options. This makes for a simpler launching command, rather than the end user needing to name the exact location of the client library. For example, this command:</p>
<div class="fragment"><div class="line">bin64/drrun -t mytool -tool_option1 -tool_option2 -- myapp</div>
</div><!-- fragment --><p>can be made to expand to this equivalent command:</p>
<div class="fragment"><div class="line">bin64/drrun -mytool_dr_option1 -mytool_dr_option2 -c tools/mytool/libmytool.so -tool_option1 -tool_option2 -- myapp</div>
</div><!-- fragment --><p>For more extensive actions on launching the tool, a custom front-end executable can be created that replaces <code>drrun</code> by using <code>drinjectlib</code>, <code>drconfiglib</code>, and <code>drfrontendlib</code>. These three libraries facilitate creating cross-platform tools for configuring and launching applications under Dr. Memory. For more information about the interfaces they provide, see their header files: <a class="el" href="dr__inject_8h.html" title="Injection API. Use these functions to launch processes under the control of DynamoRIO.">dr_inject.h</a>, <a class="el" href="dr__config_8h.html" title="Deployment API for DynamoRIO. Use these functions to register processes to run under DynamoRIO...">dr_config.h</a>, <a class="el" href="dr__frontend_8h.html" title="Tool front-end API. Use these functions to search for and query the properties of a target applicatio...">dr_frontend.h</a>.</p>
<p>A custom front-end executable can be invoked via a <code>drrun</code> <code>-t</code> configuration file using one of the following lines:</p>
<div class="fragment"><div class="line">FRONTEND_ABS=/absolute/path/to/front-end</div>
</div><!-- fragment --><p>or</p>
<div class="fragment"><div class="line">FRONTEND_REL=relative/path/to/front-end/from/DynamoRIO/root</div>
</div><!-- fragment --><p>This will cause <code>drrun</code> to transfer control to the specified front-end executable, passing any tool arguments followed by "--" and the target application command line.</p>
<p>The path to the DynamoRIO install base can be included in the front-end options via this line</p>
<div class="fragment"><div class="line">TOOL_OP_DR_PATH</div>
</div><!-- fragment --><p>The DynamoRIO runtime options can be included in a single token, preceded by a prefix, via this line, using "-dr_ops" as an example prefix:</p>
<div class="fragment"><div class="line">TOOL_OP_DR_BUNDLE=-dr_ops</div>
</div><!-- fragment --><p>A warning message can be presented up front to the user with:</p>
<div class="fragment"><div class="line">USER_NOTICE=This tool is currently experimental.  Please report issues to mytool.com/issues.</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
